intention.js

Once all the contexts have been written, Intention must search the DOM for elements that have been flagged "intentional". It will find each element and create a record of it and its manipulations in an array of objects intent.elms. Every specified manipulation will be saved in this array as instructions, so when an axis or context is passed the manipulation is more immediate.

To perform this search, first construct all of your axes and threshold groups, then run this function at doc ready.

$(function(){
  intent.elements(document);
});
         

Should you need to inject intentional HTML after the page load, you can always add elements to this registry using intent.add().

For demonstration purposes, here's an example of an object saved in the element array.

[...
↓ Object
   → elm: elementObject
   ↓ spec: manipulationsObject
      __move__:"#movementTarget" 
      __placement__:"moveMethod"
      ↓ axisName: Object
         ↓ contextName: Object
            class:"className"
            attribute:"value"
            
↓ Object
   → elm: section#output
   ↓ spec: Object
      __move__:"#input"
      __placement__:"after"
      ↓ width: Object
         standard: Object
            class:"standard"
         tablet: Object
            class:"tablet"
         mobile: Object
            class="mobile"
...]

Context.js returns the Intentional object right out of the box, so you can use it across plugins and files; but if you are just using intention.js and your own custom axes, you might want to also extend the Intentional object yourself.

Allowing the Intentional object to be used in plugins and other files is as simple as saving it to a global variable. At the end of your document, simply create a variable for the window scope that matches the variable name for the Intention object you created in the very beginning.

var intent = new Intention();

//...
//all your stuff
//...

window.intent = intent;

It's possible (and very easy) to set up event listeners for context changes. Intention.js supports event binding to scenarios such as:

1. When a specific context passes true
2. When a specific context in a specific axis passes true
3. When a specific axis passes any context

The syntax generally follows jQuery's syntax for event binding. Preface the .on() event handler with the namespace intent.

The event itself is made up of two optional parts: an axis ID and a context name. The axis ID refers to the axis' ID property and should always be followed by a : . Using the axis ID on its own will fire every time a context in that axis is passed. Specifying a context name will narrow the event to fire only when that context within that axis is passed.

Alternatively, an event handler can be created for contexts without a specified axis. Simply excluding the axis ID component (and its trailing :) will make a more general event listener for the specified context name. In this scenario, be careful of naming conflicts. If any two contexts share the same name, both will fire this same event.

Below is a list of reference IDs for the axes supplied in context.js

axis: ID
   - contexts

horizontal_axis: width
   - standard
   - tablet
   - mobile
orientation_axis: orientation
   - portrait
   - landscape
touch: touch
highres: highres

1. When a specific context passed true.

intent.on('contextName', function() {
// ...
});

intent.on('mobile', function() {
// ...
});

2. When a specific context in an specific axis passes true

intent.on('axisID:contextName', function() {
// ...
});

intent.on('width:mobile', function() {
// ...
});

3. When a specific axis passes any context

intent.on('axisName:', function() {
// where axisName is the axis' ID property
// ...
});

intent.on('width:', function() {
// ...
});

Note: currently, Intention does not support multiple event types per event handler. You will have to chain events instead.

One-time Page Load Responses

On certain occasions you may only care about the first context passed when the page first loads. After that first load, you may not want the event handler to keep firing. In this scenario, we can use jQuery's Deferred Objects.

var init = function(contexts, callback){
   var dfds = [],
   _.each(contexts, function(ctx){
      var dfd = $.Deferred();
      
      dfds.push(dfd);
      
      if(intent.is(ctx)) {
         dfd.resolve();
      } else {
         intent.on(ctx, dfd.resolve);
      }
   });
   $.when.apply(this, dfds).done(callback);
};

init(['mobile'], function() {
console.log('mobile ctx is first passed');
});
init(['standard', 'tablet'], function() {
console.log('both standard and tablet have been passed');
});

The above function init() accepts two parameters: an array of context names to be passed and a callback function that is triggered when the array is satisfied. With supplied each context, init() creates a deferred object and adds it to a master array.

If the user is already in that context when the function is called, the deferred object will be resolved. If the user is not already in that specific context, init will create an event handler to wait for the context to pass true, when it will resolve the deferred object. When all of the deferred objects in the master array have been resolved, the callback function will fire once and only once.

Repeating Event Handlers

If you do not care about the first response on page load exclusively but want to create an event handler that still affects the first response, the easiest way is to edit context.js. We want to have all event handlers be written before the affected axes respond. Otherwise, the first manipulations will have already occurred before the event handler is even created.

var intent = new Intention();

// Event handlers can be created
// before the axis is even written
intent.on('standard', function() {
//   ... 
});

var horizontal_axis = intent.responsive({
   ID: 'width',
   contexts: [
      {name:'standard', min:840}, 
      {name:'tablet', min:768},
      {name:'mobile', min:0}
   ],
   matcher: function(measure, context) {
      return measure >= context.min;
   },
   measure: function() {
      return $(window).width();
   }
});

// Just as long as they are made
// before the axis responds
// and after the intent object

intent.on('width:', function() {
//   ...
});

horizontal_axis.respond();

$(window)
.on('resize', horizontal_axis.respond);

window.intent = intent;

$(function() {
   intent.elements(document);
});

Feel like chattin' about all this? Shoot us an email or get in contact with us on Twitter (@intentionjs). Of course, there's also our GitHub, too.

MIT license for everything

Copyright (c) 2012 The Wall Street Journal,
http://wsj.com/

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.